Magnum One/Magnum One (Mid-American Digital) (Disc Manufacturing).iso/d20/doorskl3.arc/DOORSKEL.DOC

Text File | 1992-01-15 | 12KB | 254 lines

DOORSKEL.LZH Documentation
==========================


DOORSKEL is a skeleton for writing your own PC Doors in C.  The source
supports both Turbo C 2.0 and MSC 6.0a.  The Doors you write can read
either DORINFO?.DEF or XBBS' BBS-specific files.  THEY WILL WORK WITH
ANY BBS THAT USES A DORINFO?.DEF FILE AND/OR CAN PASS COMMAND LINE
ARGUMENTS; YOU ARE NOT LIMITED TO USING THESE DOORS WITH XBBS.  THEY
REQUIRE A FOSSIL DRIVER.

I'm not going to hold your hand in these docs.  If you don't know how to
program in C, either learn how first or be prepared to do your homework
as you go along.  DOORSKEL is simple to use, but it is in C, not
GWBASIC; a simple book in Greek might be hard for you to read if you
can't read Greek...

The first four .C files (DOORSKEL.C, DOORSKL2.C, DOORMISC.C and MTASK.C)
contain support and startup functions.  DOORSKL3.C contains a file
reading function.  DOORSKL4.C contains an empty function (mainloop())
which is where you start writing your own code. The main() function (in
DOORSKEL.C) calls mainloop() after it starts up the Door. By the time
mainloop() executes, the FOSSIL is hot, screen cleared and status line
displayed, command line arguments parsed, info files read and global
variables set up.  You can go to town.  When your program returns from
mainloop(), the FOSSIL is flushed and deinitialized. DOORSKL5.C contains
CRC-16 and CRC-32 code which you can use to implement file transfer
protocols or whatever.  DOORANSI.C contains some fancy ANSI input
routines, and DOORHELP.C contains user help functions.

Please take the time to look at the support functions and read the
comments in all files (including particularly DOORSKEL.H) so you don't
reinvent the wheel and see how to take advantage of what you've been
provided.  Most of the commonly asked questions (how do I do xxx when
writing a Door in C?) have been addressed, including disabling
control-break, checking carrier and time, displaying files, inputting
keys and strings, and writing to both the screen (through ANSI.SYS or
equivalent driver) and modem while maintaining a local status line.
Trust me, it's worth the time.  If you can't write a fancy Door with
what's in this thing, you may as well hang up your programming hat.

The SCREEN2.ASM/OBJ files in the archive were lifted from jim nutt's
MSGED 2.0 source code (it's marked "public domain" within an inch of its
life).  Thanks to jim (I assume he wrote it).  Turbo C's cprintf()
contains a big bug (won't write to lines below 25 in 43/50/60 line
mode), so this made it much easier.  The OBJ is compiled in large model,
but you'll note the prototypes in doorskel.h that allow you to use it
(carefully, maybe) in small models.  There's also ANSI.ASM/OBJ files in
the archive that came from the RBBS source and were heavily modified.

Although you can consider most of this code a "black box," you might
want to wedge some command line arguments into main() or add something
to the deinit() code executed when the program exit()s.  I've tried to
leave you comments about what each function does.  Hopefully the
#defines to get the code to work with either Turbo C or MSC won't get
too much in the way of your understanding.  I provided complete source
instead of some sort of library so that anything you don't like can be
adjusted.  But, please, for your own sake, make changes slowly, if at
all, to the existing code, and only after trying it out as is first!
You'll save yourself some headaches...

If you need to ask a question, send me netmail.  Poll again in a few
days for a reply.

Keep in mind what you paid for DOORSKEL before you write me just to
bitch.  On the other hand, constructive criticism, suggestions and
wish-lists are welcome.


The Doorskel archive contains SAMPLE.C, which can be used to create the
sample Door SAMPLE.EXE (also included, compiled with TC 2.0).  SAMPLE.C
is DOORSKL4.C with mainloop() (the function where your coding starts)
filled in.  This is provided as a simple example of how to use the kit
to create a running .EXE, and so you can quickly satisfy yourself that
the code works.  SAMPLE H for help on how to use it.


I've also added XBBSMSG.LZH to the archive.  This can let you write code
that interfaces directly and safely with the XBBS message bases if you've
got the urge.


Most commonly used functions:   (see prototypes in doorskel.h)
============================

hitreturn:      display "Press [Enter] to continue: " and wait for
                [Enter] to be pressed
cls:            clear local and remote screens
debug_print:    display messages locally only, and then only if debug
                mode is turned on at the command line with "!".  Handy
                for testing.
addtolog:       write a string to a logfile (default is XBBS.LOG set in
                DOORSKEL.C)
inkey:          mimics BASIC's INKEY$ function; basic method of getting
                a character from the user.  returns 0 if no char
                available.  handles special keys (like ALT-+ for more
                time, ALT-H to hang up, etc. from local, ANSI cursor and
                Doorway keys from remote)
genin:          generic input routine.  very versatile.
printfm:        printf-clone for both local and remote.
spawnit:        spawn a program.  Handles clearing screen before spawn
                and clearing screen and restoring status line after.
mainloop:       where your coding really starts, in DOORSKL4.C
printm:         print a string to local and remote; no formatting like
                printfm.
printg:         like printm but only sends string if user has ANSI
                graphics on.
mprint:         print a string to remote only, no formatting.
deinitialize:   exit routine established in DOORSKEL.C via atexit().
                disables FOSSIL, closes all files, etc.  You can add
                things to this (it's in DOORSKEL.C).
ansi:           print a string locally only; protects status line.  No
                formatting.  this function is in ANSI.ASM (compiled in
                large mode in provided ANSI.OBJ; see prototypes in
                doorskel.h).
readtext:       super-duper file reader for remote users.  try it,
                you'll like it.  It's in DOORSKL3.C and does everything
                but make coffee in the morning.
dputc:          direct screen putc
dputs:          direct screen puts (no cr/lf terminator added)
dprintf:        direct screen printf
fossil:         handles most common FOSSIL int 14H calls.  see also
                macros defined in doorskel.h for convenience.

Global variables of interest:  (already set when mainloop() executes)
============================

maxx, maxy:     width and length of the local screen.
current_color:  used by direct screen writing functions as color for
                text.
debug_mode:     if non-zero, debug_print will display text locally.
graphics:       non-zero if user has ANSI graphics capability on.
timelimit:      user's time tracking variable.  use macro MinsLeft
                (defined in doorskel.h) to get something easier to work
                with, or check getxbbstime() to see how it's used.
baud:           0 if local, otherwise baud rate of user
numlines:       length of user's screen
width:          width of user's screen
seclvl:         security level of user
commport:       port program is communicating with if baud > 0; 0-based
                so that 0 = COM1 (the way FOSSILs like it)
logfile:        name of logfile to which addtolog will write.
username:       name of user.
nodenumber:     node of caller (for multiline systems).

(#defining XBBS causes some other interesting variables to be created)


(Note:  I'll add to this list and the descriptions as I get time)



Special local keys supported by DOORSKEL:

ALT-H:  hang up, end program
ALT-J:  jump to local DOS shell
ALT-+:  increase time by 1 minute
ALT--:  decrease time by 1 minute
ALT-C:  enter/exit chat mode
CTRL-C: if DISABLEBREAK isn't defined, works as expected
CTRL-ALT-DEL: guess


Doorskel reads ANSI escape sequences from the remote for cursor
movement, and processes "Doorway" keys.  Take a look at specialmod() in
doorskel.c to see how it works.


This code does produce warnings; it's not completely "clean".  As far as
I can tell, it works fine.  It's been cobbled together from doors and
BBSes I've written, as an explanation for its slovenliness.  And
remember, I'm a self-taught ex-BASIC programmer who just does this as a
hobby.  If someone wants to clean up all the warnings and send me the
code, more power to them; I'd appreciate it.  Just don't let the
warnings scare you too much.



Log of changes:
==============

/* 10/24/91 */

Moved some functions from DOORSKEL.C to DOORMISC.C; not sure why, but I
did.  Include DOORMISC.C in any project where you include DOORSKEL.C
(read: all projects).

Added MTASK.C (routines in DOORSKEL.C call what's needed, so don't worry
about it, just include it in your project) to allow DOORSKEL doors to
get along with multitaskers (give up time slices).  SAMPLE.EXE in the
archive is still the one compiled with the old package (just too lazy to
recompile).  If you're curious but lazy (aren't we all?), reference to
set_mtask() is in main() and references to pause_mtask() are in inkey()
and my_sleep().

/* 10/27/91 */

Added DOORHELP.C and DOORANSI.C containing functions lifted from XDB's
source code.  I haven't attempted to compile these as part of a Doorskel
project, so you might have to tweak here and there.  They provide help
facilities and fancy-ANSI menus.

/* 12/01/91 */

Did some work, testing, clarification, etc. to make Doorskel smaller and
somewhat easier to read and use.  Pay particular attention to the
comments in DOORSKEL.H (now arranged in blocks so you can find the part
you're interested in more easily) and at the top of each module.
Recompiled SAMPLE.EXE with MSC this time (in small model, just to make
sure it could be done, with no optimizations). Included MSC 6.0
SAMPLE.MAK and TC 2.01 SAMPLE.PRJ files so you can reconstruct
SAMPLE.EXE for testing.  If you have a compiler other than TC 2.01 or
MSC 6.0x, hopefully the portability stuff I've already put in will make
it fairly easy to modify the code to work with your compiler.  By all
means, send me what it took to get it to work to incorporate into future
releases.

/* 12/05/91 */

Found and fixed a bug; ANSI.ASM didn't have SETFASTANSI declared PUBLIC.
Compiled under small and compact models of TC 2.01 to test compatibility
code.  Replaced MSC small model SAMPLE.EXE with TC's for the hell of it.

/* 12/16/91 */

Added another fancy input module (SELECT1.C) and modified the sample
Door to use its selection routines.  Replaced TC small model .EXE with
an MSC large model, again, for the hell of it.  Tweaked here and there.
Put the stuff that needs to be redefined for each new Door (name of
Door, interface type, etc.) into a separate THISPROJ.H file that
DOORSKEL.H includes so that you don't have to much around with
DOORSKEL.H when starting a new project.




Except where specifically noted in the source,

  DOORSKEL is copyright (c) 1990/91 by M. Kimes, All Rights Reserved.

It may be freely used for >>>FREE<<< programs as long as you don't try
to save any souls (nasty habit).  Any freely given, unsolicited
donations will go to the "buy the wife some pizza" fund.

If you want to make money on a program you write with it, give me a call
and we'll work something reasonable out.  If you want to save souls with
a program you write with it, go directly to hell.



M. Kimes
1:380/16.0@Fidonet
[phone] data